home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 001-025 / scopedisk6 / atoolsm2 / atooldoc < prev    next >
Text File  |  1995-03-18  |  6KB  |  132 lines
  1.  
  2.    BASED ON THE LATEST VERSION - RELEASE.3 - AUDIOTOOLS BY ROB PECK
  3.    ****************************************************************
  4.     Adaptation for  M2Amiga Modula-2   by Anthony Bryant   9/4/88
  5.  
  6. AudioTools is a collection of simple-to-use audio routines, that enable the
  7. user to queue up several sounds and have the audio device play them,
  8. sequentially, while your program continues doing what it was doing, without
  9. going directly to the hardware.
  10.  
  11. This provides the capability to synchronize graphics and sound.  Now when you
  12. InitAudio() - initialize the AudioTools - a return value must be saved so that
  13. it can be used later to FinishAudio(), as well as passed with the function
  14. procedure named MayGetNote().   You can identify a note by number, an id, using
  15. PlayNote(), PlayFreq() or PlaySamp(), then tell MayGetNote() whether you want
  16. to get a return immediately, if there is no identified note available to be
  17. gotten, or if you want your task to wait until there is something to be
  18. returned.  Additional procedures simplify operations on individual channels.
  19.  
  20. The AudioTools module has the appearance of a normal library module consisting
  21. of a symbol file (sym/AudioTools.sym) and an object file (obj/Audiotools.obj)
  22. from which you can IMPORT the following procedures.
  23.  
  24. The procedures: 
  25.  
  26.  port:= InitAudio();        initialize the audio routines, get a port
  27.                 for receiving messages from audio routines
  28.                                 
  29.  chan:= GetChannel(type);    request a channel to use.
  30.   
  31.  error:= FreeChannel(chan);    free a channel that you have been given.
  32.   
  33.  FinishAudio(port);        end the use of audio routines and return
  34.                 the port you received from audio routines
  35.                                 and free up allocated CHIP RAM.
  36.  
  37.  error:= StopChannel(chan);    temporarily halt a channel you own.
  38.  error:= StartChannel(chan);    start your channel up again.
  39.  error:= FlushChannel(chan);    empty the queue of a channel from any notes
  40.                 it is playing or is going to play.
  41.  error:= ResetChannel(chan);    reset a channel
  42.  
  43.  error:= IsThatMyChan(chan);    see if your task still owns a particular
  44.                                 channel (audio system allows stealing of
  45.                                 channels if the are not locked at a high
  46.                                 enough priority).
  47.  flag:= CheckIfDone();          check if all notes are finished playing.
  48.                                   
  49.  id:= MayGetNote(port, flag);   see if a note you marked has begun to play.
  50.                 possibly put task to sleep if flag = TRUE
  51.                 good for synchronizing graphics and sound.
  52.  
  53.  error:= SetPV(channel,per,vol); set the period and/or volume of a channel
  54.                 that is already playing a waveform.
  55.  
  56.  error:= SetWave(chan,waveArray);  set up waveform, an ARRAY [0..255] OF BYTE,
  57.                                    in CHIP RAM to play on specific channel.
  58.  
  59.   error:= SetSamp(chan,sample,length); copy sample data BYTES to CHIP RAM
  60.                                  to play on specific channel .. unless..
  61.                                  if length = 0 then just free up previous sample
  62.                                  if sample (ADDRESS) = 0 then return new value
  63.                                  in VAR sample - without copying data.
  64.                                     
  65.   PlayNote( ... parameters ...)  queue up a specific note number to be played
  66.                  by one of your channels.
  67.   PlayFreq( ... parameters ...)  queue up a specific frequency instead of note.
  68.  
  69.   PlaySamp( ... parameters ...)  queue up a sample to play instead of note.
  70.   
  71.   where ( ... parameters ...) = 
  72.        (channel,note/freq/per,volume,duration,priority,messageport,id)
  73.   
  74. (See DEFINITION MODULE (AudioTools.def) for parameter types and specifics)
  75.  
  76. The error conditions:
  77.  
  78.  InitAudio()    returns a NIL pointer if OpenDevice() or CreatePort() failed.
  79.  
  80.  GetChannel()   normally returns specific channel number 0,1,2 or 3 UNLESS
  81.                 returns (notYourChannel) if channel already busy
  82.                 returns (badChannelSelected) if unit failed to be assigned
  83.                 returns -10  ADIOERR_NOALLOCATION if WaitIO() failed
  84.  
  85. IsThatMyChan()  normally returns 0 if valid channel you own UNLESS
  86.                 returns (badChannelSelected) if chan not 0,1,2 or 3
  87.                 returns (notYourChannel) if channel already busy
  88.                 
  89. other Channel procedures and also SetPV() procedure 
  90.                 returns  same as IsThatMyChan() errors and also
  91.                 returns -10  ADIOERR_NOALLOCATION if WaitIO() failed
  92.                         
  93. IF (CheckIfDone() = FALSE) THEN notes not finished playing
  94. IF (CheckIfDOne() = TRUE ) THEN o.k. all finished
  95.  
  96. SetWave()      normally returns 0 if everything went o.k. UNLESS
  97.                returns same as IsThatMyChan() errors and also
  98.                returns (outOfMemory) if AllocMem() failed
  99.                
  100. SetSamp()      same as SetWave()
  101.  
  102. (See IMPLEMENTATION MODULE (AudioTools.imp) for the complete source code. )
  103.  
  104. Using the AudioTools routines:
  105.  
  106. FROM AudioTools IMPORT
  107.  
  108. PROGRAM MODULE (AudioDemo.mod) contains the complete source to a simple demo
  109. showing the usage for each of the many commands that make AudioTools easy to
  110. use.  AudioDemo is the executable file.
  111.  
  112. -------------------------------------------------------------------------------
  113.   The C source for AudioTools was kindly placed into the public domain by 
  114.   
  115.   Rob Peck, thanks Rob!   This M2Amiga Modula-2 adaptation, source, symbol and
  116.   
  117.   object library module files, including demo is also now in the public domain.
  118.   
  119.   Audiotools is being revised, so this adaptation is based on RELEASE.3, the
  120.   
  121.   latest (and greatest) version.  In the fullness of time, it is to be hoped,
  122.   
  123.   AudioTools will become a shared library (loadable from disk), but in the
  124.   
  125.   meantime I will try to keep this M2 directory up-to-date with the latest
  126.   
  127.   Release from Rob.
  128.   
  129.                                   Anthony Bryant   9/4/88
  130.   -----------------------------------------------------------------------------
  131.   
  132.